Technotes

Download Acrobat file (135K)

Download ClarisWorks 4 file (39K)

QuickView version not available yet

T E C H N O T E : Inside Macintosh: Processes: Time Manager Addenda

Updated by Quinn "The Eskimo!"
Apple Developer Technical Support
28 March 1997

This Note highlights the usage of two fields -- tmReserved and tmWakeUp -- that might be unclear after reading the chapter "Time Manager" in Inside Macintosh: Processes.

Setting Up tmReserved

theTMTask.tmWakeUp = theTMTask.tmReserved = 0;
InsXTime((QElemPtr)&theTMTask);
PrimeTime((QElemPtr)&theTMTask, 2000);

The truth is that prior to October, 1992 (System Software 7.1), you didn't care, but it's more of a concern now, since Apple slightly modified the behavior of the Time Manager to deal with performance issues.

If you leave tmReserved untouched, then, after 127 calls to the following code:

RmvTime((QElemPtr)&theTMTask);
remaining = theTMTask.tmCount;
InsXTime((QElemPtr)&theTMTask);
PrimeTime((QElemPtr)&theTMTask, 0);

So, if you perform that kind of time measurement, be sure to write instead:

RmvTime((QElemPtr)&theTMTask);
remaining = theTMTask.tmCount;
theTMTask.tmReserved = 0;
InsXTime((QElemPtr)&theTMTask);
PrimeTime((QElemPtr)&theTMTask, 0);

About tmWakeUp

Warning:

Since the format of that field is undocumented and used internally by the Time Manager, developers are strongly discouraged anyway from performing any kind of calculation or comparison on the value of this field, since that format could change in the future.

Undeferred Time Manager Tasks

This section describes an optimization that you might want to employ when using the Time Manager in the presence of virtual memory (VM). Most developers will not be interested in this; however, all users of the Time Manager should heed the following warning.

Important

Because there is an extremely remote possibility that the memory you've allocated for your Time Manager task contains the special value listed below, if you want to ensure the behavior defined in Inside Macintosh: Memory, you should always clear the qLink field in the TMTask before installing it.

As described in Inside Macintosh: Memory, Time Manager tasks are automatically deferred by the Virtual Memory (VM) system to avoid double page faults. This was done for backward compatibility with existing applications that use the Time Manager, but it can seriously increase the latency between when the timer expires and when your Time Manager task executes.

For more information about interactions between the Time Manager and VM, see Technote 1094, "Virtual Memory Application Compatibility".

For example, if you set a Time Manager task to execute at time X and, at time (X - delta) some process takes a page fault, your Time Manager task will not be called until time (X + Y - delta), where Y is the time required to field a page fault. If the page fault causes the hard disk to seek, Y could be as great as the hard disk's average seek time, approximately 10ms. If you are trying to use the Time Manager to measure time in microseconds, this could be a problem.

There is a way you can install Time Manager tasks so the callback is not deferred by VM; however, before using this technique, you should be aware of the dangers. Because VM does not defer these special Time Manager tasks, it is possible for them to fire when paging is not safe. To avoid fatal page faults, you must ensure:

• The TMTask record is held for the entire time the Time Manager task is installed. You can do that using the following code:

        HoldMemory(&theTask, sizeof(TMTask));

• The code for the timer task and any data it references is held. If the code for your timer task is stored in a code resource, you can use the following snippet to make sure it is held. If your timer task code is not in a code resource, it's very difficult to ensure that it and its data are held.

        // Ensure the code doesn't move in logical memory
        HLock(ttaskCodeHandle);
        // Ensure the code is held in physical memory and cannot be paged to disk
        HoldMemory(*ttaskCodeHandle, GetResourceSizeOnDisk(ttaskCodeHandle));

• You timer task code only calls system routines that are guaranteed to meet the above requirement -- this typically means only that routines that are known to be interrupt-safe.

Important

If you fail to meet these requirements, you will cause a fatal page fault and crash the system.

If you call InsTime or InsXTime with the qLink field set to $65616461, the VM patch on the Time Manager will recognize your special requirements and execute your timer task as soon as it fires, regardless of whether paging is safe or not.

Another Way to Perform Time Measurement

pascal void Microseconds(UnsignedWide *microseconds);

Warning:

Currently, even with the most recent system software (7.5.3 revision 2) on a PCI Power Macintosh, both the Time Manager calls and the Microseconds call are still in 68K code and thus are executed by the emulator. If you call them from PowerPC code, you'll get a switch from PowerPC code to the 68K emulator, so the values returned are incorrect by a few tenths of a microsecond. This means that you have to be careful when using either of them to do time measurement. If you do use Microseconds, then your time measurement is done by the difference of the 2 values returned by Microseconds before and after the code you measure, and since the latency induced by the switches is the same in both case, then your time measurement is correct. If you do use the Time Manager way of performing time measurement, however, the tmCount field may be off by a few tenths of a microsecond.

Summary

• Always set tmReserved to 0 before calling InsXTime.
• Set tmWakeUp to 0 before the first call to InsXTime, never look at it or modify it (except to set it to 0 in some cases, no other value is acceptable) afterwards.
• tmCount is only valid after a call to RmvTime.
• Always clear qLink before calling InsXTime.
• Microseconds might be a good alternate way.

Further Reference

• Inside Macintosh: Processes, Chapter 3, The Time Manager
• Denis G. Pelli's Web page

Acknowledgments

Thanks to Brian Bechtel, Drew Colace, Denis G. Pelli and Bob Wambaugh.